<h1>Redirect on Error</h1>
<p>Sometimes, you may wish to redirect users to a different URL when an API endpoint returns an error status code (400-599). The <code>mx-redirect-on-error</code> attribute makes this process straightforward.</p>

<h2>Usage</h2>
<p>Simply add <code>mx-redirect-on-error</code> to any element that triggers an HTTP request (such as forms or buttons) and set its value to "true". The redirect URL should be returned as plain text in the response body from your server.</p>

<div class="alert alert-warning">
  <p>The redirect happens immediately upon receiving an error response from the target API endpoint. Because of this, <code>mx-redirect-on-error</code> should <b>not</b> be combined with animation attributes or other error handlers since they won't have time to execute.</p>
</div>

<h3 class="mt-3">Basic Example:</h3>
<p>In the example below, clicking a form button invokes an HTTP POST request.  If the server responds with an HTTP response code that is in the <b>success</b> range, the element with an id of 'result' will be updated.  However, if the server responds with an HTTP response code in the <b>error</b> range, the user will be redirected to the URL that is specified in the response body.</p>
[code=vf]
&lt;?php
$btn_attr = [
  'mx-post' =&gt; 'products/delete/123',
  'mx-target' =&gt; '#result',
  'mx-token' =&gt; $trongate_token,
  'mx-redirect-on-error' =&gt; 'true'
];
echo form_button('delete_btn', 'Delete Product', $btn_attr);
?&gt;

&lt;div id="result"&gt;&lt;/div&gt;
[/code]

<p class="mt-3 mb-0">Here's an alternative syntax, for users who prefer to work with pure HTML:</p>

[code=vf]
&lt;button mx-post="products/delete/123"
        mx-target="#result"
        mx-token="&lt;?= $trongate_token ?&gt;"
        mx-redirect-on-error="true"&gt;Delete Product&lt;/button&gt;

&lt;div id="result"&gt;&lt;/div&gt;
[/code]

<div class="alert alert-info">
  <p>The code sample above assumes that a <code>$trongate_token</code> value has been passed into the view file from a controller file.</p>
</div>

<h2>Server-Side Implementation</h2>
<p>For the error redirect to work correctly, your API endpoint must:</p>
<ol>
  <li>Return an error status code (400-599).</li>
  <li>Return only the redirect URL as plain text in the response body.</li>
</ol>

<h3 class="mt-3">Example Controller Code:</h3>
[code=php]
public function delete_product($product_id) {
  $this->module('trongate_tokens');
  $trongate_token = $this->trongate_tokens->_attempt_get_valid_token();

  if ($trongate_token === false) {
    http_response_code(401);
    echo 'auth/login'; // Will redirect to yoursite.com/auth/login
    die();
  }
  
  if ($this->products->delete($product_id)) {
    http_response_code(200);
    echo 'Product deleted successfully.';
  }
}
[/code]

<h2>Common Use Cases</h2>
<h3>1. Login Form</h3>
[code=vf]
&lt;div id="response"&gt;&lt;/div&gt;

&lt;?php
$form_attr = [
  'mx-post' =&gt; 'members/submit_login',
  'mx-target' =&gt; '#response',
  'mx-redirect-on-error' =&gt; 'true'
];
echo form_open('#', $form_attr);

$username_attr['placeholder'] = 'Enter username here...';
echo form_input('username', '', $username_attr);

$password_attr['placeholder'] = 'Enter password here...';
echo form_password('password', '', $password_attr);

echo form_submit('submit_btn', 'Login');
echo form_close();
?&gt;
[/code]

<h3>2. Protected Resource Access</h3>
[code=vf]
&lt;?php
$btn_attr = [
  'mx-get' =&gt; 'products/view/999',
  'mx-target' =&gt; '#product-details',
  'mx-redirect-on-error' =&gt; 'true'
];
echo form_button('view_product_btn', 'View Product', $btn_attr);
?&gt;

&lt;div id="product-details"&gt;&lt;/div&gt;
[/code]

<div class="alert alert-warning">
  <p><b>A few friendly reminders:</b></p>
  <ul>
    <li>Make sure your response body contains only the URL - any additional content will prevent the redirect from working properly.</li>
    <li>The redirect happens straight away when an error response is received.</li>
    <li>You can't use this with error animation attributes since the redirect happens immediately.</li>
    <li>For handling successful scenarios, consider using <code>mx-redirect-on-success</code>.</li>
  </ul>
</div>

<h2>URL Handling</h2>
<p>You can specify the redirect URL in several ways:</p>
<ul>
  <li>Relative to your site root (e.g., 'auth/login').</li>
  <li>Starting with a forward slash (e.g., '/auth/login').</li>
  <li>As an absolute URL (e.g., 'https://example.com/auth/login').</li>
</ul>

<div class="alert alert-info">
  <p class="mt-0"><strong>Tip:</strong> For relative URLs to work properly, make sure your page includes a <code>&lt;base&gt;</code> tag in the head section. For example:</p>
  [code=html]
  &lt;base href="&lt;?= BASE_URL ?&gt;"&gt;
  [/code]
  <p>Without a base tag, relative URLs might not resolve to the correct location.</p>
</div>

<div class="alert alert-success">
  For seamless navigation flows, consider using both <code>mx-redirect-on-error</code> and 
  <code>mx-redirect-on-success</code> together to handle both successful and failed scenarios.
</div>

<h2>Summary</h2>
<p>The <code>mx-redirect-on-error</code> attribute provides a simple way to handle error scenarios in your web applications. It is especially useful for managing authentication failures, missing resources, or any situation where you need to gracefully redirect users to a different page when things don't go as planned.</p> 
<p>Best of all, no extra JavaScript is required — simply return a URL from your API endpoint, and you're good to go! Whether you're building a complex authentication system or a simple form handler, this attribute helps create smooth, user-friendly experiences with minimal effort.</p> 